
// Qt link color to put in css: #00732f
/**
    \mainpage StarMenu - QML contextual menu plugin - Version 1.0
    \author Marco Bavagnoli <lil.deimos@gmail.com>

    \section intro_sec Introduction

    \brief StarMenu - QML contextual menu plugin

    \ref component_starmenu is a contextual pop up menu that can be raised by clicking
    or tapping on an area defined like using \c MouseArea component. StarItems are entries for the
    %StarMenu like MenuItems are for Menu component.
    This plugin is been developed with Qt 4.7.4 and tested on linux, Nokia N900, Nokia C7-00,
    Nokia N950 and Android Galaxy tab GT-7310 (with <a href="https://sourceforge.net/p/necessitas/home/necessitas/">Necessitas</a>).\n
    <b>Note for Harmattan:</b>
    .pro file must contains this:\n
    
    contains(MEEGO_EDITION,harmattan) {\n
        DEFINES += MEEGO_EDITION_HARMATTAN \n
        QT += dbus \n
    }\n

    \section Usage

    <b>To compile and install the plugin, just do:</b> \n
    qmake \n
    make \n
    make install \n
    \n
    then in your .qml you will need to \n
    import com.starMenu 1.0 \n

    <b>To compile within your project:</b>\n
    copy staritem.* and starmenu.* in your project directory and add them to the .pro file.\n
    Then in the \a main.cpp include the headers:\n
    \code
    #include "starmenu.h"
    #include "staritem.h"
    \endcode
    \n
    and before \a setSource() or \a setMainQmlFile() register the component with:\n
    \code
    qmlRegisterType<StarMenu>("StarMenu", 1, 0, "StarMenu");
    qmlRegisterType<StarItem>("StarMenu", 1, 0, "StarItem");
    \endcode
    then, in your .qml file, you will be able to:\n
    \code
    import StarMenu 1.0
    \endcode


    \image html images/StarMenu_two_starsubmenu.jpg

    The \ref component_starmenu displays a contextual menu in a declarative user interface.

    A %StarMenu is hidden by default and opens in response to a user action. The purpose of
    %StarMenu is to manage all %StarItem childs. By default they are arrange in a circle shape
    and, in the center of it, it is painted a star polygon shape with as many spikes as
    the number of StarItems. It can be visible or not by setting the boolean \c starCenterVisible property. \n
    The circle shape amplitude is given by \c radiusH and \c radiusV properties. \n
    Clicking on the center of the current menu, will close it and goes back to parent. \n
    It's possible to click on the center of the first menu to close all. \n
    \c visualParent property is used to bind the close menu action to a specified item, so, instead of clicking
    on center of StarMenu, it's possible to set \c visualParent to the main window and close menu everywhere on the screen. \n
    When using \c visualParent, it come handy the \c color property to set a transparent color to the clickable area to close the menu. \n
    Changing StarItem \c visible property, makes all StarItems position recalculated with only visible items. \n


    \code
    StarMenu {
      id: starMenu
      anchors.fill: parent
      visualParen: mainWindow
      color: Qt.rgba(0, 0, 0, 0.7)
      radiusH: 130
      radiusV: 130

      StarItem {
         width: 64; height: 64
         Image {
           anchors.fill: parent
           [...]
         }
      }
       StarItem {
       [...]
         StarMenu {
           [...]
         }
       }
    }
    \endcode
    \n\n

    \image html images/StarMenu_rotation_scale_delayed_animation.jpg
    \n
    It is possible to bind animations to StarItems. When a %StarMenu is raised, all StarItems have the
    center by the mouse (or tap) position and their \c opacity, \c rotation, \c x, \c y property are set to 0. \n
    By doing this:
    \n
    \code
    StarItem {
            [...]
            Behavior on x { NumberAnimation { duration: 1500; easing.type: Easing.OutBounce } }
            Behavior on y { NumberAnimation { duration: 1500; easing.type: Easing.OutBounce } }
            Behavior on opacity { NumberAnimation { duration: 2200 } }
            [...]
    \endcode
    \n
    StarItems are animated from center to their final position. \n
    It is also possible to animate \ref component_starmenu rotation:

    \code
    StarMenu {
          id: starMenu2
          anchors.fill: parent; smooth: true
          radiusH: 80
          radiusV: 80
          starCenterVisible: false
          rotation: 1000
          onStarMenuOpening: rotation = 0
          onStarMenuClosing: rotation = 1000
          Behavior on rotation { NumberAnimation { duration: 3000; easing.type: Easing.OutQuad } }
          […]
    \endcode
    %StarMenu has a \c delayChangePos property. For example, when it is set to 100, the animation of
    the second StarItem is started after 100 ms, the third StarItem after 200 ms and so on.
    %StarItem has also a \c delayChangePos property and if it is set, it takes priority over the %StarMenu \c delayChangePos property.
    \n
    \image html images/StarMenu_components_inside.jpg
    \n
    On right example above, a \c visualParent property is set to the root view; the user can close the menu by
    clicking on the visualParent item (in this case the main window).\n
    StarItems can also contain any other component then Images, and components could be created dynamically by for example a rss feed:
    \code
    StarItem {
       width: 320; height: 240
       scale: 0.3
       zoomHoverValue: 1
       Behavior on scale { NumberAnimation { duration: 500; easing.type: Easing.OutQuad } }
       Column {
            Button { text: "Hello Qt" }
            Switch { }
            RadioButton { }
       }
    }
    \endcode
    \n
    \image html images/StarMenu_shapes.jpg
    \n
    StarItems can also be arranged in a spiral shape, grid shape or line shape.
    %StarMenu shape property could have the following values:
    \li StarMenu.ShapeCircle (default value)
    \li StarMenu.ShapeGrid
    \li StarMenu.ShapeSpiral
    \li StarMenu.ShapeLine

    Rows in grid shape are arranged centered by the mouse click and are spaced by \c spacingH and \c spacingV properties with columns count defined by \c columns property.
    Spiral shape takes care of \c startingRadius value to start drawing StarItems and \c radiusIncrement property to shape the spiral.
    Line shape has a \c startingAngle, \c radiusIncrement and \c startingRadius properties.

    %StarMenu has the center where user clicks. This center could be defined everywhere in scene coordinates by setting \c center property.

    http://www.youtube.com/watch?v=Z54zgOod0P0










\n\n\n\n
\section component_starmenu StarMenu component

\section prop_starmenu_sec Properties

    \li \ref prop_center
    \li \ref prop_color
    \li \ref prop_columns
    \li \ref prop_delayChangePos
    \li \ref prop_open
    \li \ref prop_radiusH
    \li \ref prop_radiusV
    \li \ref prop_rotation
    \li \ref prop_radiusIncrement
    \li \ref prop_shape
    \li \ref prop_spacingH
    \li \ref prop_spacingV
    \li \ref prop_startingAngle
    \li \ref prop_endAngle
    \li \ref prop_starCenterVisible
    \li \ref prop_startingRadius
    \li \ref prop_useParentMenuCenter
    \li \ref prop_visualParent



\section signal_sec Signals

    \li \ref signal_starMenuOpening
    \li \ref signal_starMenuClosing


\n
\n
\section prop_starmenu_docs Properties Documentation


    \subsection prop_center center: point
    Center coordinates relative to the root scene.

    \subsection prop_closeDelay closeDelay: int
    Set the delay to close the menu.

    \subsection prop_color color: color
    Color of the sensible area to be clicked to close the menu. Useful if \c visualParent is defined.

    \subsection prop_columns columns: int
    Columns when \c ShapeGrid is used.

    \subsection prop_delayChangePos delayChangePos: int
    Delay between each StarItems positioning after the mouse click. If \c delayChangePos property of %StarItem has priority over this.

    \subsection prop_endAngle endAngle: qreal
    Used with ShapeCircle to define the angle of the last item+1 (this mean that in the circle shape, the last and the first item, does not overlap).
    Default value is 360.

    \subsection prop_open open: bool
    Set or get open state of %StarMenu. The value is true only when the %StarMenu is the current.
    Every parents and childs %StarMenu have this property set to false. Usually the %StarMenu is opened by user action.

    \subsection prop_openDelay openDelay: int
    Set the delay to open the menu.

    \subsection prop_parentVisible parentVisible: bool
    Setting this to true, the parent menu will still be visible. Useful when building a dropdown like menu. Default is false.

    \subsection prop_radiusH radiusH: qreal
    Horizontal radius of the circle shape.

    \subsection prop_radiusV radiusV: qreal
    Vertical radius of the circle shape.

    \subsection prop_rotation rotation: qreal
    Rotation of StarItems. Only available with circle and spiral shapes.

    \subsection prop_radiusIncrement radiusIncrement: qreal
    Used with spiral and line shapes to define spacing betweeen StarItems.

    \subsection prop_shape shape: enumeration
    Shape to be used. The default is ShapeCircle.
    \li StarMenu.ShapeCircle
    \li StarMenu.ShapeGrid
    \li StarMenu.ShapeSpiral
    \li StarMenu.ShapeLine

    \subsection prop_spacingH spacingH: qreal
    Used with ShapeGrid to space horizontally StarItems.

    \subsection prop_spacingV spacingV: qreal
    Used with ShapeGrid to space vertically StarItems.

    \subsection prop_startingAngle startingAngle: qreal
    Used with ShapeLine to define the direction of the StarItems and with ShapeCircle to define the angle of the first item.
    Default value is 0.

    \subsection prop_starCenterVisible starCenterVisible: bool
    Show the star at the center of %StarMenu. The star shape  has as many spikes as the number of StarItems.

    \subsection prop_startingRadius startingRadius: qreal
    Used with ShapeSpiral and with ShapeLine to define the distance from center of the first StarItem.

    \subsection prop_useParentMenuCenter useParentMenuCenter: bool
    When true, the center of the StarMenu will be the center of parent %StarMenu if exists.

    \subsection prop_visualParent visualParent: Item
    The Item in which the user will click to close the %StarMenu.
    The default sensible area is the parent of %StarMenu, with the \c visualParent, developers
    are able to redefine this area for example to the main application window.


\n
\n
\section signal_starmenu_docs Signals documentation


    \subsection signal_starMenuOpening StarMenu::starMenuOpening()
    Signal for detecting StarMenu opening.

    \subsection signal_starMenuClosing StarMenu::starMenuClosing()
    Signal for detecting StarMenu closing.


\n
\n
\n
\n
\section component_staritem StarItem component

\section prop_staritem_sec Properties

    \li \ref prop_staritem_zoomHoverValue
    \li \ref prop_staritem_delayChangePos

\section signal_staritem_sec Signals

    \li \ref signal_staritem_hoverItem
    \li \ref signal_staritem_leaveItem
    \li \ref signal_staritem_clicked


\n
\n
\section prop_staritem_docs Properties Documentation
    \subsection prop_staritem_zoomHoverValue zoomHoverValue: qreal
    Zoom value when mouse enters.

    \subsection prop_staritem_delayChangePos delayChangePos: int
    Delay between %StarItem is positioned after the mouse click. If this property is set, it will take priority over the same StaMenu property.

\section signal_staritem_docs Signals Documentation

    \subsection signal_staritem_hoverItem StarItem::hoverItem()
    Signal for detecting when mouse is hover.

    \subsection signal_staritem_leaveItem StarItem::leaveItem()
    Signal for detecting when mouse leaves.

    \subsection signal_staritem_clicked StarItem::clicked()
    Signal for detecting a mouse click.

*/
